issue-parser

What is issue-parser?

The issue-parser npm package is designed to parse issue references from commit messages, pull requests, and other text. It helps in extracting and managing issue references in a structured way.

What are issue-parser's main functionalities?

Parsing Issue References

This feature allows you to parse issue references from a given text. In this example, the text 'Fixes #123' is parsed to extract the issue reference '#123'.

const issueParser = require('issue-parser')();
const result = issueParser('Fixes #123');
console.log(result);

Customizing Issue Patterns

This feature allows you to customize the patterns for issue references. In this example, the parser is configured to recognize 'gh-' as a valid issue prefix.

const issueParser = require('issue-parser')({
  issuePrefixes: ['#', 'gh-'],
  issueURLSegments: ['issues', 'pull']
});
const result = issueParser('Fixes gh-123');
console.log(result);

Parsing Multiple Issue References

This feature allows you to parse multiple issue references from a single text. In this example, the text 'Fixes #123, closes #456' is parsed to extract both issue references '#123' and '#456'.

const issueParser = require('issue-parser')();
const result = issueParser('Fixes #123, closes #456');
console.log(result);

Other packages similar to issue-parser

parse-commit-message

The parse-commit-message package is used to parse and validate commit messages according to the Conventional Commits specification. It provides a structured way to handle commit messages, similar to how issue-parser handles issue references.

commitlint

The commitlint package is used to lint commit messages based on predefined rules. It ensures that commit messages follow a specific format, which can include references to issues. While it doesn't parse issue references directly, it helps maintain a consistent format that can be parsed by tools like issue-parser.

README

issue-parser

Parser for Github, GitLab and Bitbucket issues actions, references and mentions

The parser can identify:

• GitHub closing keywords, duplicate keyword, issue references and user mentions
• GitLab closing keywords, duplicate keyword, issue references and user mentions
• Bitbucket closing keywords, issue references and user mentions

Install

$ npm install --save issue-parser

Usage

GitHub format

const issueParser = require('issue-parser');
const parse = issueParser('github');

issueParser('Issue description, ref user/package#1, Fix #2, Duplicate of #3 /cc @user');
/*
{
  refs: [{raw: 'user/package#1', slug: 'user/package', prefix: '#', issue: '1'}],
  actions: [{raw: 'Fix #2', action: 'Fix', prefix: '#', issue: '2'}],
  duplicates: [{raw: 'Duplicate of #3', action: 'Duplicate of', prefix: '#', issue: '3'}],
  mentions: [{raw: '@user', prefix: '@', user: 'user'}],
}
*/

GitLab format

const issueParser = require('issue-parser');
const parse = issueParser('gitlab');

issueParser('Issue description, ref group/user/package#1, implement #2, /duplicate #3 /cc @user');
/*
{
  refs: [{raw: 'group/user/package#1', slug: 'group/user/package', prefix: '#', issue: '1'}],
  actions: [{raw: 'implement #2', action: 'Implement', prefix: '#', issue: '2'}],
  duplicates: [{raw: 'Duplicate of #3', action: 'Duplicate of', prefix: '#', issue: '3'}],
  mentions: [{raw: '@user', prefix: '@', user: 'user'}],
}
*/

Bitbucket format

const issueParser = require('issue-parser')
const parse = issueParser('bitbucket');

issueParser('Issue description, ref user/package#1, fixing #2. /cc @user');
/*
{
  refs: [{raw: 'user/package#1', slug: 'user/package', prefix: '#', issue: '1'}],
  actions: [{raw: 'fixing #2', action: 'Fixing', prefix: '#', issue: '2'}],
  duplicates: [],
  mentions: [{raw: '@user', prefix: '@', user: 'user'}],
}
*/

Custom format

const issueParser = require('issue-parser')
const parse = issueParser({referenceActions: ['complete'], issuePrefixes: ['🐛']});

issueParser('Issue description, related to user/package🐛1, Complete 🐛2');
/*
{
  refs: [{raw: 'user/package🐛1', slug: 'user/package', prefix: '🐛', issue: '1'}],
  actions: [{raw: 'Complete 🐛2', action: 'Complete', prefix: '🐛', issue: '2'}],
  duplicates: [],
  mentions: [],
}
*/

Features

Parse references

#1

{refs: [{raw: '#1', slug: undefined, prefix: '#', issue: '1'}]}

Parse repository slug

owner/repo#1

{refs: [{raw: 'owner/repo#1', slug: 'owner/repo', prefix: '#', issue: '1'}]}

Parse closing keywords

Fix #1

{actions: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]}

Parse duplicate keywords

Duplicate of #1

{duplicates: [{raw: 'Duplicate of #1', action: 'Duplicate of', slug: undefined, prefix: '#', issue: '1'}]}

Parse user mentions

@user

{mentions: [{raw: '@user', prefix: '@', user: 'user'}]}

Ignore keywords case

FIX #1

{actions: [{raw: 'FIX #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]}

Ignore references in back-tick quotes

Fix #1 `Fix #2` @user1 `@user2`

{
  actions: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}],
  mentions: [{raw: '@user1', prefix: '@', user: 'user1'}]
}

Include references in escaped back-tick quotes

\`Fix #1\` \`@user\`

{
  actions: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}],
  mentions: [{raw: '@user1', prefix: '@', user: 'user1'}]
}

Ignore references in fenced blocks

Fix #1

```js
console.log('Fix #2');
```

@user1

```js
console.log('@user1');
```

{
  actions: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}],
  mentions: [{raw: '@user1', prefix: '@', user: 'user1'}]
}

Include references in escaped fenced blocks

\`\`\`
Fix #1
\`\`\`

\`\`\`
@user
\`\`\`

{
  actions: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}],
  mentions: [{raw: '@user', prefix: '@', user: 'user'}]
}

Ignore references in <code> tags

Fix #1
<code>Fix #2</code>
<code><code>Fix #3</code></code>
@user1
<code>@user2</code>

{
  actions: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}],
  mentions: [{raw: '@user1', prefix: '@', user: 'user1'}]
}

Include references in escaped <code> tags

`<code>`Fix #1`</code>`
`<code>`@user`</code>`

{
  actions: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}],
  mentions: [{raw: '@user', prefix: '@', user: 'user'}]
}

Ignore malformed references

Fix #1 Fix #2a Fix a#3

{actions: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]}

API

issueParser([options]) => parse

Create a parser.

options

Type: Object String
Parser options. Can be github, gitlab or bitbucket for predefined options, or an object for custom options.

referenceActions

Type: Array<String> String
Default: ['close', 'closes', 'closed', 'closing', 'fix', 'fixes', 'fixed', 'fixing', 'resolve', 'resolves', 'resolved', 'resolving', 'implement', 'implements', 'implemented', 'implementing']

List of action keywords used to close issues and pull requests.

duplicateActions

Type: Array<String> String
Default: ['Duplicate of', '/duplicate']

List of keywords used to identify duplicate issues and pull requests.

mentionsPrefixes

Type: Array<String> String
Default: ['@']

List of keywords used to identify user mentions.

issuePrefixes

Type: Array<String> String
Default: ['#', 'gh-']

List of keywords used to identify issues and pull requests.

parse(text) => Result

Parse an issue description and returns a Result object.

text

Type: String

Issue text to parse.

Result

actions

Type: Array<Object>

List of issues and pull requests closed.
Each action has the following properties:

Name	Type	Description
raw	String	The raw value parsed, for example Fix #1.
action	String	The keyword used to identify the action, capitalized.
slug	String	The repository owner and name, for issue referred as <owner>/<repo>#<issue number>.
prefix	String	The prefix used to identify the issue.
issue	String	The issue number.

duplicates

Type: Array<Object>

List of issues and pull requests marked as duplicate.
Each duplicate has the following properties:

Name	Type	Description
raw	String	The raw value parsed, for example Fix #1.
action	String	The keyword used to identify the duplicate, capitalized.
slug	String	The repository owner and name, for issue referred as <owner>/<repo>#<issue number>.
prefix	String	The prefix used to identify the issue.
issue	String	The issue number.

refs

Type: Array<Object>

List of issues and pull requests referenced, but not closed or marked as duplicates.
Each reference has the following properties:

Name	Type	Description
raw	String	The raw value parsed, for example Fix #1.
slug	String	The repository owner and name, for issue referred as <owner>/<repo>#<issue number>.
prefix	String	The prefix used to identify the issue.
issue	String	The issue number.

mentions

Type: Array<Object>

List of users mentioned.
Each mention has the following properties:

Name	Type	Description
raw	String	The raw value parsed, for example Fix #1.
prefix	String	The prefix used to identify the mention.
user	String	The user name

allRefs

Type: Array<Object>

List of all issues and pull requests closed, marked as duplicate or referenced.
Each reference has the following properties:

Name	Type	Description
raw	String	The raw value parsed, for example Fix #1.
action	String	The keyword used to identify the action or the duplicate, capitalized.
slug	String	The repository owner and name, for issue referred as <owner>/<repo>#<issue number>.
prefix	String	The prefix used to identify the issue.
issue	String	The issue number.